…Env env

Adds envs/harbor_env, which runs any Harbor task directory
(https://www.harborframework.com/docs/tasks) as a Gymnasium-style OpenEnv
environment. The task directory is the interface: a directory that
`harbor run` accepts is served unchanged — no conversion step, no second copy
of the data, and no producer-specific code in OpenEnv. That covers
Terminal-Bench-lineage tasks and everything Repo2RLEnv generates from a GitHub
repository, so a task set built for evaluation is also a training environment.

Design
------
The environment is deliberately thin and split by concern:

  task.py     parses task.toml and discovers task directories
  sandbox.py  Harbor's sandbox contract; local and docker backends
  reward.py   Harbor's reward-file contract
  harbor_env_environment.py  reset/step/state over the three above
  app.py      FastAPI

Rewards are always produced by the task's own tests/test.sh and only forwarded,
per OpenEnv's rewards-in-environment invariant. reward.json is read first and
reward.txt is the fallback, matching Harbor. A verifier that writes no reward
file yields reward=None and an explicit error rather than a fabricated 0.0,
which would be indistinguishable from a genuine failure and would poison
training data.

exec/read/write are the agent's action space; evaluate and solve are
orchestration controls and are never exposed to the agent, keeping the dual API
boundary intact. read and write are confined to the working directory so an
agent cannot reach /tests or /solution, and the verifier log directory is
cleared immediately before the verifier runs so a planted reward file cannot
survive into the score.

Two backends: `local` runs subprocesses under a per-episode directory tree with
Harbor's paths exported as HARBOR_* variables (no Docker, so it works on HF
Spaces), and `docker` runs inside the task's own image, which is required for
tasks whose starting state lives in an image. Local mode refuses image-backed
tasks with an actionable message instead of grading an empty directory, and is
documented as a filesystem boundary rather than a security one.

Task sets load from a local directory or straight from a Hugging Face dataset
(hf://datasets/<org>/<name>[@rev]), including the tasks/<id>/ layout that
`repo2rlenv push` writes.

Verification
------------
The bundled examples/tasks/fix-sum-bug task is written to run under every
runtime and grades identically on all three — 0.600 untouched, 1.000 after
solution/solve.sh — under `harbor run` (harbor 0.20.0), harbor_env local mode,
and harbor_env docker mode.

A real Repo2RLEnv-emitted pr_runtime task (produced by repo2rlenv's own
emitter: version = "1.0", [metadata.repo2env], environment/Dockerfile with
WORKDIR /workspace, tests/test.sh writing /logs/verifier/reward.txt) scores 0.0
for a no-op agent and 1.0 for the oracle under both `harbor run` and
harbor_env docker mode, with reward-details.json surfaced intact as
observation.info["reward_details"].

tests/envs/test_harbor_env.py adds 50 hermetic tests (no Docker, no network)
covering task parsing including Repo2RLEnv's `version` spelling, catalog
discovery, the reward-file precedence chain, workdir escape rejection, the
agent/orchestration boundary, and the client/server wire contract. Full suite:
1463 passed, 130 skipped.

Also adds examples/quickstart.py, examples/validate_taskset.py (an oracle sweep
to run before training on a generated task set), the docs stub, and the
environment catalog entry.

…ion, empty paths

Cursor Bugbot and Copilot both reviewed huggingface#1018. Four concrete findings, all real:

1. reset() left the previous episode in state (Bugbot, medium)
   close() tears the sandbox down first, but _state was only replaced after
   catalog.get() and sandbox.start(), either of which can raise. A failed reset
   therefore reported a task_id, workdir and reward for an episode that was no
   longer running. Now drops to a clean HarborState before the fallible work.

2. DockerSandbox.upload_dir() archived nested files twice (Copilot)
   rglob("*") yields directories as well as files and tarfile.add() recurses by
   default, so every nested file was added once via its parent and again on its
   own iteration. Passes recursive=False; directory entries are still emitted,
   so empty directories survive.

3/4. read/write accepted an empty path (Copilot; write was filed low-confidence)
   HarborAction.path defaults to "", which resolve_within() happily resolved to
   the working directory itself. For read that produced a confusing
   "no such file: ". For write it was destructive: the target split into
   ("/", "workspace"), so the upload would have dropped a regular file over the
   whole checkout. Fixed in resolve_within() rather than at the two call sites,
   since that is the single chokepoint every agent-supplied path passes through
   — "", "   ", "." and "a/.." are all rejected now.

Also, from Copilot's Tier 2 flag that evaluate/solve share the action schema
with agent actions: AGENT_ACTIONS and CONTROL_ACTIONS were decorative — exported
but never referenced. HarborActionType is now composed from AgentActionType and
ControlActionType instead of restating the five strings, so a new action has to
be classified as one or the other to exist at all, and a test asserts the two
sets remain a partition of the handler table. That does not resolve the
boundary question itself, which is left for human review.

Tests: 8 added (58 total). Each regression test was confirmed to fail against
the unfixed code before being kept. Full suite 1471 passed, 130 skipped.

…isode terminal

Addresses the three issues raised in review, plus two related holes found while
verifying them.

## [p1] local mode was the default and leaked too much

- `HARBOR_MODE` now defaults to `docker`. It is the faithful backend and the
  only one that can enforce a task's declared policies; `local` is an explicit
  opt-in for Docker-less hosts such as Spaces.
- `LocalSandbox.exec` no longer hands subprocesses the server's whole
  environment. Task commands are attacker-controlled input, so they now start
  from a short allowlist (PATH, HOME, LANG, …) and the process's API keys and
  Hub tokens stay out. A task that needs a secret declares it in
  `[environment].env`, which is resolved explicitly.

While confirming the escape, two further leaks turned up:

- `reset()` put the task's server-side directory in the observation, which
  reaches the agent. In local mode `exec cat <path>/solution/…` then read the
  oracle outright. `HarborTask.summary()` no longer carries `path`;
  `HarborState.task_path` still does, since state is infrastructure-side.
- `HARBOR_TESTS_DIR` / `HARBOR_SOLUTION_DIR` / `HARBOR_LOGS_DIR` were exported
  into agent commands. `SandboxPaths.as_env(agent_visible=True)` now withholds
  them; the verifier and oracle still receive the full set.
- `stage_tests` / `stage_solution` now wipe the destination first. The agent
  shares the filesystem and could pre-create `/tests`; a planted file survived
  staging and was read by the verifier. Regression test confirms it scored 1.0
  before this change.

## [p1] network, resource and user policies were ignored

`task.py` now parses `[environment].network_mode` / `allowed_hosts` / `cpus` /
`memory_mb` / `storage_mb` / `gpus` / `workdir` and `[agent].user` /
`[verifier].user`, including the deprecated `allow_internet` spelling.

- Docker: `no-network` becomes `network_mode="none"`, cpus/memory become real
  container limits, and each phase runs as its declared user. Verified against a
  live container — `getent hosts pypi.org` fails and `memory.max` reads
  536870912.
- Unenforceable policies are refused rather than approximated: `allowlist`
  (needs a filtering proxy) and `gpus`. An unknown `network_mode` is a parse
  error, so it can never silently degrade to `public`.
- Phases that disagree get the restrictive setting — a container has one
  network, and resolving that conflict permissively would hand a sandboxed
  verifier the internet.
- Local: refuses any task declaring a policy it cannot enforce, naming
  HARBOR_MODE=docker, instead of running it unconstrained and reporting a score
  the task never sanctioned.

## [p2] evaluate/solve split unenforced; done walked back

- After `evaluate` the episode is terminal: every later action is refused and
  keeps reporting `done=True`. Previously a post-evaluate `exec` returned
  `done=False`, contradicting a terminal state already reported to the trainer.
- `allow_control_actions` (env `HARBOR_ALLOW_CONTROL_ACTIONS=0`) makes the
  server refuse `evaluate`/`solve` outright, so the agent/orchestration split is
  enforced rather than left to the caller's wiring. Left on by default, since a
  run that cannot score itself is only useful for agent-facing deployments.

Tests: 14 added (72 total). Each regression test was confirmed to fail against
the unfixed code. Existing tests now pass `mode="local"` explicitly rather than
relying on the old default. Full suite 1578 passed, 131 skipped.

Self-review of the policy work found that honouring [agent].user broke every
task that declares one. The Harbor directories are created by the image's
default account, so an agent running as `nobody` inherited a working directory
it could not write to: `touch probe.txt` returned Permission denied, and every
`write` action would have failed. The same applied to [verifier].user and
/logs/verifier, which would have left those tasks unscorable.

Sandbox.chown() now hands the working directory and agent log dir to the agent
user at start, and the verifier log and tests dirs to the verifier user before
the verifier runs. Verified against a live container: the agent is `nobody`, the
workdir is writable, and the task still grades 0.6.

Also notes that storage_mb needs a quota-capable storage driver; where one is
absent Docker rejects the container, which is the fail-closed outcome.

…ardening

A rubber-duck pass over 592de2b/270a4579 found that several of those fixes were
incomplete, and that one of them had silently defanged an existing test.

## The oracle was still reachable in local mode

Removing `path` from `HarborTask.summary()` was not enough: `HarborState`
carried `task_path`, and `state` rides the same socket as `step`. A caller that
could act could still read the host path and `cat <path>/solution/…`. The field
is gone.

## read/write bypassed [agent].user entirely

`read_text()` ran `cat` as the image's default account and `write_text()`
extracted a root-owned tar through the archive API, so a task declaring an
unprivileged agent still got root's reach through those two actions.
Demonstrated before the fix: a symlink in the working directory plus `read`
returned `/etc/shadow`, and plus `write` created a root-owned file under
`/root`. Both now run as the declared user, with writes going through the shell
so the kernel applies its permissions. Re-verified against a live container —
both attempts are refused and agent-written files are owned by `nobody`.

## Failed evaluation left the tests exposed and the episode running

`evaluated` was set only after staging, chowning and executing, so a failure in
between left `/tests` readable with `done=False`. The episode now terminates
before anything that can fail.

## storage_mb was not fail-closed

Docker accepts `storage_opt` on drivers that never enforce it — the review
demonstrated a 64 MiB write inside a 32 MiB "limit". A task that believes it is
capped and is not is worse than one told up front we cannot cap it, so this is
now refused like `allowlist` and `gpus`.

## Malformed limits read as "no limit"

`_positive_int` turned `0`, `-4` and `"lots"` into `None`, which meant both an
unconstrained container *and* no refusal from the local backend. Invalid values
are now `TaskFormatError`.

## Phase overrides did not replace the baseline

`NetworkPolicy.modes` unioned the baseline unconditionally, so a task whose
agent and verifier both declared `public` over a `no-network` baseline had its
network disabled anyway. Only the effective per-phase modes count now.

## An existing security test had gone vacuous

`test_planted_reward_files_are_discarded` planted through `$HARBOR_LOGS_DIR`,
which 592de2b hid from agent commands — so the plant silently failed and the
test passed for the wrong reason. It now uses the real path and asserts the
plant landed before checking it is discarded.

## Smaller

- Agent-supplied `timeout_s` is capped at the configured ceiling instead of
  overriding it; it arrives on the wire and was unbounded.
- `validate_taskset.py` passes `allow_control_actions=True` — it *is* the
  orchestration, and was inheriting the deployment's flag.
- The README no longer claims local mode keeps secrets from tasks. It keeps them
  out of the environment, but `/proc/<ppid>/environ` still exposes them; that is
  hygiene, not containment, and is now described as such.

Tests: 78 (5 added). Full suite 1584 passed, 131 skipped.

Cursor and Copilot both flagged the same hole independently, and they were
right: `resolve_within()` is a purely lexical check, so it cannot see a symlink
the agent planted with `exec`. Demonstrated before the fix:

    exec  ln -s <tests dir> link
    read  path="link/grade.py"   -> returned the grader's source

That defeats the documented guarantee that `/tests` and `/solution` are
unreachable through `read`/`write` — the agent could read the grading logic, and
`write` could plant files the verifier would then execute.

Agent paths now go through `Sandbox.resolve_agent_path()`, which keeps the
lexical check and then canonicalizes on the sandbox's own filesystem:
`Path.resolve()` locally and `readlink -m` in the container. `-m` rather than
`-f` because a `write` may legitimately create directories that do not exist
yet, while symlinks that *do* exist are still resolved — which is the only part
confinement depends on.

The base is canonicalized too. Without that the fix rejected everything on
macOS, where the episode root lives under `/var`, itself a link to
`/private/var`. Both cases are covered by tests.

Also, from the same round of review:

- Local mode now flags a task that declares `[environment].docker_image` while
  running on the host toolchain. Seed files make the *state* reproducible, but
  the image supplies the toolchain, and a version skew would otherwise surface
  as a mis-graded episode. Warned in the log and surfaced in the reset
  observation as `info["toolchain_warning"]`.

Two other items from that round needed no change:

- "Failed evaluate leaves the episode open" was reported against 270a457 and
  was already fixed in dd2232b, which terminates before the verifier runs.
  Verified: a task with no `tests/test.sh` returns `done=True`, as does every
  action after it.
- "PathLike task source crashes" does not reproduce. `pathlib.Path` is hashable,
  so `lru_cache` accepts it; `resolve_task_source(Path("..."))` resolves
  normally.

Tests: 81 (3 added). The symlink test was confirmed to fail against the
pre-fix lexical check. Full suite 1587 passed, 131 skipped.